[release-1.7.3]: https://github.com/HuolalaTech/page-spy-web/releases/tag/v1.7.3
[public-data-event]: https://github.com/HuolalaTech/page-spy/blob/main/docs/plugin_zh.md#行为约定

import modalImg from '@/assets/image/screenshot/modal.png';
import replayImg from '@/assets/image/screenshot/replay-page.png';
import replayGif from '@/assets/image/screenshot/replay-page.gif';
import mpDataHarborImg from '@/assets/image/screenshot/mp-data-harbor.png';

## What is it#what

Log replay is an offline debugging feature that allows you to view and analyze runtime data from when an issue occurred. By replaying historical logs, you can recreate the problem scenario like watching a video recording, without needing to be connected to the debugging client in real-time.

<a href={replayGif} target="_blank">
  <img src={replayGif} />
</a>

## Why#why

While PageSpy's online debugging is powerful, it requires the client and debugging endpoint to be online simultaneously. This brings some limitations:

- **High personnel cost**: Requires developers and testers to be online simultaneously for debugging a single issue
- **Unstable connections**: Client moving to background or network fluctuations can cause disconnections
- **Real-time transmission pressure**: Need to consider data volume and network transmission performance

To solve these issues, PageSpy introduced the log replay feature in [version 1.7.3][release-1.7.3], making debugging more flexible and free.

## Getting Started#start-using

### Used in browser#browser

If you need the full functionality of PageSpy, including online debugging and offline replay, integrate as follows:

#### Step 1: Integrate SDK and plugins#step-1

```html
<html>
  <head>
    <!-- 1. Load PageSpy -->
    <script src="{deployUrl}/page-spy/index.min.js"></script>

    <!-- 2. Load DataHarbor plugin: cache offline log data, provide upload/download functionality -->
    <script src="{deployUrl}/plugin/data-harbor/index.min.js"></script>

    <!-- 3. Load RRWeb plugin: record user operations (optional) -->
    <script src="{deployUrl}/plugin/rrweb/index.min.js"></script>

    <script>
      // 4. Register plugins, see config details at: https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-data-harbor
      PageSpy.registerPlugin(new DataHarborPlugin(config));
      PageSpy.registerPlugin(new RRWebPlugin());

      // 5. Instantiate PageSpy
      window.$pageSpy = new PageSpy({
        // To avoid establishing a real-time connection between the SDK and the debugger, enable offline mode
        // offline: true
      });
    </script>
  </head>
</html>
```

After successful integration, the PageSpy floating ball will appear in the bottom right corner of the page. Clicking the floating ball will show a popup with upload and download buttons.

<a href={modalImg} target="_blank">
  <img src={modalImg} />
</a>

Click the upload or download button to save the offline log data.

#### Step 2: Replay logs#step-2

Go to the debugging client, click the top menu "Start Debugging - Log Replay" to enter the replay list page. Select the JSON data uploaded/downloaded in the previous step to start replaying!

<a href={replayImg} target="_blank">
  <img src={replayImg} />
</a>

#### Plugin Description#plugins

- **DataHarborPlugin**: Collects and stores offline log data, provides upload/download functionality
- **RRWebPlugin** (optional): Uses [rrweb]({VITE_PLUGIN_RRWEB}) to record DOM updates and user operations. In the "Log Replay" panel on the debugging client, you can see the page operation recording on the left side

### Using O-Spy#use-ospy

If you only need the offline log replay functionality, we recommend using [O-Spy](/o-spy). It is a plug-and-play SDK that requires no server deployment, with built-in best practice configurations for PageSpy, DataHarborPlugin, and RRWebPlugin.

It is framework-agnostic, and you can choose any method to integrate it:

import { ImportGuide } from '@/pages/OSpy/components/ImportGuide';

<ImportGuide />

Once successfully integrated, you will see a draggable "Issue Feedback" component appear in the bottom right corner.

#### Custom Theme Example#customize-example

import { CustomizeExample } from '@/pages/OSpy/components/Customize';

<CustomizeExample />

### Used in mini-program#mp

Mini-program environments also support offline log replay. Follow these steps:

#### Step 1: Install mini-program specific plugin#mp-step-1

```bash
yarn add @huolala-tech/page-spy-plugin-mp-data-harbor
```

#### Step 2: Register the plugin#mp-step-2
```ts
import PageSpy from '@huolala-tech/page-spy-wechat';
import DataHarborPlugin from '@huolala-tech/page-spy-plugin-mp-data-harbor';

// register the plugin, see config details at：https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-mp-data-harbor
const $dataHarborPlugin = new DataHarborPlugin(config)
PageSpy.registerPlugin($dataHarborPlugin);

const $pageSpy = new PageSpy({
  // ...
})

```

#### Step 3: Upload offline logs#mp-step-3

There are two ways to upload offline logs:

**Method 1: Code invocation**

```ts
$dataHarborPlugin.upload().then(() => {
  console.log('Upload successfully');
})
```

**Method 2: Use debugging menu**

After registering the mini-program DataHarbor plugin, a "Upload Offline Log" button will appear in the PageSpy debugging menu. Click to upload:

<a href={mpDataHarborImg} target="_blank">
  <img style={{width: 375}} src={mpDataHarborImg} />
</a>

## Extended Reading#read-more

### How it works#how-it-works

Log replay is implemented based on the [DataHarborPlugin]({VITE_PLUGIN_DATA_HARBOR}) plugin. This plugin listens to the [`"public-data"` event](./plugins#convention) inside PageSpy to automatically collect all data generated at runtime.

### Platform Differences#platform-differences

Different platforms have the following differences in log replay functionality:

| Feature | Browser | Mini-program |
| --- | --- | --- |
| Data upload | ✅ Supported | ✅ Supported |
| Data download | ✅ Supported | ❌ Not supported |
| UI recording (RRWebPlugin) | ✅ Supported | ❌ Not supported |

### FAQ#faq

#### 1. How to manually upload/download logs?

See detailed instructions in the [DataHarborPlugin API documentation](./data-harbor#onOfflineLog).

#### 2. Where is offline log data stored?

The processing flow after DataHarborPlugin receives data:

1. Data is first stored in a memory array
2. When the data in memory reaches a threshold (default 10MB), it is automatically written to a temporary file
3. Users can upload data to the server or download it locally at any time

You can customize the memory threshold:

```ts
new DataHarborPlugin({
  maximum: 1 * 1024 * 1024, // Write to temp file when data in memory reaches 1MB
})
```

#### 3. Will offline logs affect application performance?

DataHarborPlugin has been performance optimized:

- Uses asynchronous processing, does not block the main thread
- Automatically controls memory usage to prevent memory overflow
- Data is compressed before storage to reduce space usage